Skip to main content

Concepts

Property Definition#

In order to link properties to entities, the user should use property names. Property definitions name is unique and can't be changed. Example: For linking properties

{  "Name": "PropertyDefinitionName",  "Value": 3}

Format#

Property definition has a format field that is required and must be one of these values.

[text, boolean, integer, decimal, date, classification]

The format specifies the type of property value, which the user wants to save, and fields that property definition can have.

  • If format = text, then the user can specify also regex and regexErrorMessage fields to validate user inputs. If the input value does not match the regex the system will show regexErrorMessage value as an error message

  • If format = integer/decimal, then the user must specify a unit value, which must be from the given list [ampere, candela, kelvin, kilogram, metre, mole, second, centimetre, gram, kilowatt, megawatt, litre, cubicMetre, coulomb, radian].

  • If format = classification, then the user must link classification to the property by giving its Id.

And vice versa(e.g., if the format is classification then the property can't have regex or regex error message)

The values and formats.

  • If format = text, then the value must be text and match regex
  • If format = boolean, then the value must be boolean(true or false)
  • If format = integer, then the value must be an integer (e.g. 10)
  • If format = decimal, then the value must be decimal (e.g. 10.4)
  • If format = date, then value must be date (e.g. 10/10/2021 12:12:12)
  • If format = classification, then the value must be the name of the classification element. Classification element must be linked to classification which is linked to property definition.
  • If format = entity, then must be specified entityType (e.g. identity). If entityType is identity then the value must be object owner. Entity format properties also can be multiselect, if isMultiselect is true, then the value must be an array of object owners.

Examples:

  • Classification format

Given that user has this classification in the system

{  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  "name": "classification",  "format": "hierarchy",  "elements": [    {      "name": "element 1",      "children": [        {          "name": "element 1.1"        }      ]    }  ]}

We can use this classification in the property definition

{  "name": "propertyDefiniton",  "format": "classification",  "classification": {    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  }}

Then for linking it with other entities we can use the element name

{  "name": "propertyDefiniton",  "value": "element 1.1"}
  • Entity format

This object owner exists in the system

{  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  "name": "My team"}

We also have a property definition where the entityType is identity

{  "name": "propertyDefiniton",  "format": "entity",  "entityType": "identity"}

Then for linking it with other entities we can use the object owner

{  "name": "propertyDefiniton",  "value": {    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",    "name": "My team"  }}

Application rule#

Properties can be linked to other entities. The entity type is specified in the Application Rule field, which is required and must be from the given list(the lists are specified in microservices)

Required#

The "Required" field specifies whether the value is required

Example: If property definition ("A") required field is true

{  "Name": "A",  "Value": null}

Then this JSON is invalid because the value is required.

Default Value#

The system allows specifying default values. When the user links property definition to other entity and leaves the value null, then the system will use default value instead.

Note: Property definition can't have default value, and be required(required = true)

Note: If format = classification then default value must be the name of its elements. See format section → "The values and formats" for an example.

Example:

Property definition

{  "name": "defaultValueName",  "format": "text",  "defaultValue": "Some value"}

When the user links it to an entity

{  "name": "defaultValueName",  "value": null}

Then the system will take the default value of property definition if it exists.

{  "name": "defaultValueName",  "value": "Some value"}

Value expression#

Value expression is a JavaScript function body which takes properties linked to the same entity as parameters. It means that the value depends on other properties that user can reference and some computation. The string provided in the ValueExpression must be valid JavaScript-code of the function body with a return statement.

{  //..... JS function body  return xXx;}

Another property is referenced by using it's name. E.g., If the user wants to reference a property with the name "Prop1", then the reference would look like: Prop1

Example the user has this property definition

{  //property definition  "name": "Prop3",  "valueExpression": "{return (Prop1+Prop2)*3 + 15}"}

When the user links properties to some entity

{  //model that contains properties  "properties": [    {      "name": "Prop1",      "value": 2    },    {      "name": "Prop2",      "value": 100    },    {      "name": "Prop3",      "value": null    }  ]}

As a value of "Prop3" will be evaluated result of it's value expression JavaScript code.

{  "properties": [    {      "name": "Prop1",      "value": 2    },    {      "name": "Prop2",      "value": 100    },    {      "name": "Prop3",      "value": 321 // (100+2)*3 + 15    }  ]}

Instruction, instruction image#

For having guide/instruction on property definitions there is an instruction field in property definition and separate endpoint for instruction image. Instruction image will be visible from the frontend only if the property definition it is linked to also has an instruction. If it has an instruction image but not an instruction it won't be visible from the frontend.

Instruction image is stored in base64 format.

For updating image the following endpoint is used:

PUT /PropertyDefinitions/{id}/InstructionImage endpoint

For getting instruction image the following endpoint is used:

GET /PropertyDefinitions/{id}/InstructionImage endpoint

InstructionImageEndpoint

Metadata#

Metadata is a JSON field inside Property Definitions which doesn't have any validation and can be used to keep additional information about the property.

{  "metadata": {    "visibleByDefault": true,    "isMultiLine": true  }}

Metadata field exists in Monitors, Signals, Assets and Designations APIs.

When user wants to see input of property definition with text format as long text(multiline) in FE then isMultiLine should be specified in metadata field.

Category#

The category is for grouping property definitions.

{  "category": {      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",      "name": "string"    }}

There is one category with the name 'Ungrouped' and that is the default category. This means that when a user creates a property definition and sets the category to null, the 'Ungrouped' category will be set by default.

Note that this category can be updated and its name can be changed, but it will be the default category with any name.

Filtering#

Filtering by properties#

To filter entities by properties, users construct queries with this template {propertyName} {comparisonOperator} {value} {logicalOperator}, that contains the following parts:

  • propertyName*: the name of the property definition to filter with
  • comparisonOperator*: the comparison operator to use when filtering. Possible values include:
    • eq: equal to
    • ne: not equal to
    • gt: greater than
    • ge: greater than or equal to
    • lt: less than
    • le: less than or equal to
    • in: contains any value in an array
  • value*: the value to use when evaluating the filter
  • logicalOperator: the logical operator used to chain multiple queries together. Possible values include:
    • and: and logical operator
    • or: or logical operator

Note that fields marked with * are required.

Here's an example query: prop1 eq 'value' and prop2 gt 30. This query would filter entities where the prop1 property is equal to "value" and the prop2 property is greater than 30.

Notes:

  • Text and date values must be enclosed in single quotes (') at the beginning and end of the value. For example: prop1 eq 'value1'
  • When using the in comparison operator, the array of values must be defined within parentheses () and separated by commas. For example: prop1 in ('value1', 'value2', 'value3')
  • When filtering for null values, use the keyword null (without quotes). For example: prop1 eq null

When constructing queries, it's important to ensure that the property name and value are formatted correctly and that the correct comparison and logical operators are used.

Ordering#

To order entities, users construct queries with this template {fieldName} {orderingType}, {fieldName} {orderingType}, ..., that contains the following parts:

  • fieldName*: The name of the field to order by. It can be a field from the canonical model or a property field.
    • Canonical model: Matches the filed name in the DTO, if it is nested field then . is used e.g. ObjectOwner.name asc.
    • Properties: For properties, use the properties. prefix. Note that ordering by multi-select classification properties are not available.
  • orderingType*: The ordering type can be one of the following:
    • asc: ascending
    • desc: descending

Note that fields marked with * are required.

For example, the query status asc, properties.prop1 desc will order entities by status in ascending order, and then by prop1 in descending order.

Notes:

  • Ordering queries can be chained by commas (,) without limitation. For example: properties.prop1 desc, properties.prop2 desc, .. , properties.propN desc.
  • Ordering by multi-select classification properties are not available.
  • To sort items based on their classification properties, you have several options based on specific fields of classification elements. For example properties.classificationProp1.displayName asc. If no field is chosen it filters by name. These fields include:
    • name
    • displayName
    • code
    • applierCode
    • color
    • order
    • grade

Unique values#

Query parameters

  • fieldNames (required): Comma-separated list of field names for which to retrieve unique values. For property definitions, the prefix properties. should be used. Example: fieldNames=properties.myProperty, status
  • ids (optional): Comma-separated list of entity ids to get unique values
  • excludeIds (optional): Comma-separated list of entity ids to not include in unique values

Response format

The response will be a JSON array containing objects for each specified field name and their corresponding unique values. Each object will have two properties:

  • displayName: The human-readable display name for the value.
  • value: The value that can be used to filter entities.

E.g. for objectOwner the displayName will be the name of the user and the value will be the id.

Entity type Definition#

Types are for grouping entities and having type specific configurations for them.

User Statuses#

User Statuses provide the mechanism to expand upon system statuses and establish meaningful connections between them. This flexibility allows for the creation of custom statuses, like "In Review," which can be linked to existing system statuses such as "Active." This approach enhances a more nuanced representation of the entity's status throughout its lifecycle.

The DTO looks like this:


[  {    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",    "order": 1,    "name": "New",    "status": "new"  },  {    "id": "4e54d50f-e992-44d1-94ef-8d5690e266af",    "order": 2,    "name": "InReview",    "status": "active"  }]

Property Definitions field#

Types can have linked property definitions to it. By linking property definitions user specifies which properties can be used in the entity.

Only those property definitions can be linked to Type that has appropriate application rule.

Icon#

Icon's name is a key of icon that is agreed with FE. Icon's color is a HEX color.

General Type#

In the system, by default, exists default type called "General" and all entities are linked to it by default. General type will be chosen by default when creating an entity.